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-TITLE USER_SYS_DISP = Example of user system service dispatcher 
“IDENT “yOa=00;" : r : . 


COPYRIGHT (c) 1978, 1980, 1982, 1984 BY 
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASSACHUSETTS. 
ALL RIGHTS RESERVED. 


THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPI 
ONLY IN ACCORDANCE WITH THE TERMS OF _ SUCH bithe Ben ene othe 
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TRANSFERRED. 
THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE 
eRPORAT bn NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT 


DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 
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: Facility: Example of User Written System Services 
; Abstract: 


This module contains an example dispatcher for user written 

system services along with several sample services and a user _ 
rundown example. It is a template intend to serve as the starting 
point for implementing a privileged shareable image containing your 
own services. When used as a template, the definitions and code 
for the sample services should be removed. 


Overview: 


User written system services are contained in privileged shareable 
images that are Linked into user program images in exactly the 

same fashion as any shareable sange The creation and installation 
of a privileged, shareable image is slightly different from that 

of an ordinary shareable image. These differences are: 


1. A vector eet rareg the entry points and providing other 
control information to the image activator. This vector 
a6 8 tne lowest address in an image section with the VEC 
attribute. 


2. The shareable image is Linked with the /PROTECT option 
that marks all of the image sections $0 that they will 
prevectes and given EXEC mode ownership by the image 
activator. 


3. The shareable image MUST be installed /SHARE gy be 9 
with the INSTALL ytit ty in order for the image act 
to connect the pr 


vator 
vileged shareable image to the change mode 
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dispatchers. 


A privileged shareable (nee implementing user written system services 
is comprised of the following major components: 


1. A transfer vector containing all of the entry points and 
collecting them at the lowest virtual address in the shareable 
image. This formalism enables revision of the shareable 
my Anihcaecne necessitating the relinking of images that 
use it. 


A Privileged Library Vector in a PSECT with the VEC attribute 
that describes the entry points for dispatching EXEC and 
KERNEL mode services along with validation information. 


~m 
e 


Ww 
. 


A yee for kernel mode services. This code will 
be called by the VMS change mode dispatcher when it 
fails to recognize a kernel mode service request. 


4. A ye tre go! for executive mode services. This code will 
be called by the VMS change mode dispatcher when it fails 
to recognize an executive mode service request. 


5. Service routines to perform the various services. 


The first four components are contained in this template and are 
most easily implemented in MACRO, while the service routines can 
be implemented in BLISS or MACRO. Other panguages | be usable 

but are not recommended -- particularly if they nome re runtime 

support routines or are extravagant in their use of stack or are 
unable to generate PIC code. 


This example is position-independent (PIC) and it is good practice 


Revision Histo 


to implement shareable images this way whenever possible. 
ry: 

v04-001 wMC0001 Wayne Cardoza 06-Sep-1984 
Make system version a weak reference. 

v03-002 KDM0074 Kathleen D. Morse 23-Aug-1983 


Use cpu-dependent routine to get the TODR value. 
Add $SSDEF and remove $PRDEF. 


v03-001 ACG0001 Andrew C. Goldstein 23-May-1983 
Fix change-mode dispatcher to clean two extra longwords 
off stack before calling user system service. 


Link Command File Example: 


$! Command file to Link User System Service example. 
$ LINK/PROTECT/NOSYSSHR/ SHARE =USS/MAP=USS/FULL SYSSINPUT/OPTIONS 


o02602006000620062990069980090008 


+ 
- & 


nn 


> 


m 


> 
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SeGe See Se ee Ge Ge Ge ee ee 


: Options file for the Link of User System Service example. 
SYSSSYSTEM:SYS.STB/SELECTIVE 


Create a separate cluster for the transfer vector. 


CLUSTER= TRANSFER VECTOR, , ,SYSSDISK:CJUSSDISP 
GSMATCH=LEQUAL,1,1 


.PAGE 
-SBTTL Declarations and Equates 
Include Files 


-LIBRARY ‘‘SYSSLIBRARY:LIB.MLB"’ ; Macro Library for system structure 
3; definitions 


Macro Definitions 


DEFINE_SERVICE = A macro to make the appropriate entries in several 
ifferent PSECTs required to define an EXEC or KERNEL 
mode service. These include the transfer vector, 
the case table for dispatching, and a table containing 
the number of required arguments. 


DEF INE_SERVICE Name,Number_of Arguments ,Mode 


-MACRO DEFINE SERVICE ,NAME .NARG=0 ,MODE=KERNEL 
-PSECT $SS$TRANSFER_VECTOR, PAGE ,NOWRT EXE ,PIC 
«ALIGN QUAD } ation entry points for speed and style 
. TRANSFER NAME ; Define name as universal symbol for entry 
«MASK NAME ; Use entry mask defined in main routine 
IF IDN MODE ,KERNEL 
se #<KCODE_BASE+KERNEL_COUNTER> ; Change to kernel mode and execute 
n 


; Retur 
KERNEL_COUNTER=KERNEL_COUNTER+1 ; Advance counter 
-PSECT KERNEL_NARG,BYTE ,NOWRT,EXE,PIC 
NARG 


BYTE ; Define number of required arguments 

-PSECT re KERNEL_DISP1,BYTE,NOWRT,EXE,PIC 

. WORD +NAME-KCASE_BASE ; Make entry in kernel mode CASE table 

~IFF 

cone #<ECODE _BASE+EXEC_COUNTER> Protea to executive mode and execute 
; Return 

EXEC_COUNTER=EXEC_COUNTER+1 ; Advance counter 

~-PSECT EXEC_NARG, BYTE ,NOWRT EXE ,PIC : 

-BYTE  WNARG ; Define number of required arguments 

-PSECT USER_EXEC_DISP1,BYTE,NOWRT,EXE,PIC 

“WORD 2¢*NAME~ECASE_BASE ; Make entry in exec mode CASE table 
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-ENDC 
-ENDM DEF INE_SERVICE 


3 Equated Symbols 
SPHDDEF ; Define process header offsets 
SPLVDEF ; Define PLV offsets and values 
SSSDEF ; Define system status codes 
: Initialize counters for change mode dispatching codes 
KERNEL _COUNTER=0 ; Kernel code counter 
EXEC_COUNTER=0 ; Exec code counter 
: Own Storage 
-PSECT KERNEL_NARG,BYTE ,NOWRT,EXE PIC 
KERNEL _NARG: ; Base of byte table containing the 


;__number of required arguments. 
-PSECT EXEC_NARG, BYTE ,NOWRT EXE ,PIC 
EXEC_NARG: ; Base of byte table containing the 
; number of required arguments. 


- PAGE 
we -SBTTL Transfer Vector and Service Definitions 
The use of transfer vectors to effect entry to the user written system services 
enables some mG grt of the shareable image containing them without necessitating 
a re-link of all programs that call them. The PSECT containinng the transfer 
vector will be positioned at the lowest virtual address in the shareable image 
and so long as the transfer vector is not re-ordered, programs Linked with 
one version of the shareable image will continue to work with the next. 


Thus as additional services are added to a privileged shareable image, their 
definitions should be added to the end of the following List to ensure that 
rograms using previous versions of it will not need to be re-Llinked, 
re) owe 4 pg avoid relinking existing programs the size of the privileged 
shareable =e must not change so some padding will be required to provide 
the opportunity for future growth. 
Service to get value of time 


DEFINE_SERVICE USER_GET_TODR,1,KERNEL ; 
3; _of day register 
DEFINE_SERVICE USER_SET_PFC,2,KERNEL ; Service to set value of process 


default pagefault cluster 
DEFINE SERVICE USER_NULL,O,EXEC Null exec service 


Bete Ge Ge Ge Ge Se Se Ge Ge Oe Ge ee OHS 


The base values used to generate the dispatching codes should be nrsstive for 
user services and must be chosen to avoid overlap with any other privileged 
shareable images that will be used concurrently. Their definition is | 
deferred to this point in the assembly to cause their use in the preceetng 

; macro calls to be forward references that guarantee the size of the change 
mode instructions to be four bytes. This satisfies an assumption that is 
made by for services that have to wait and be retried. The PC for retry ing 
the change mode instruction that invokes the service is assumed to be 4 bytes 
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; less than that saved in the change mode qacopt ren frame. Of course, the particular 


3; service routine determines whether this 


Ss possible. 


KCODE_BASE=-1024 ; Base CHMK code value for these services 
ECODE_BASE=-1024 ; Base CHME code value for these services 


a 
+ 


-PA 
-SBTTL Change Mode Dispatcher Vector Block 


This vector is used by the mage activator to connect the privileged shareable 


; image to the VMS change mode d 


spatcher. The offsets in the vector are self- 


relative to enable the construction of position independent images. The system 
version number will be used by the image activator to verify that this shareable 
() 


image was Linked with the sym 


l table for the current system. 
Change Mode Vector Format 


Gee eeoceeeooeeoeoen eerererec sr ceeeceoce See c eee eaoesa a 

! Vector ype Code ! —- PLVSL_TYPE 

: (PLV$C_TYP_CMOD) H 

! System Version Number ! — PLVSL_VERSION 
! (SYS$K_VERSION) : 

tees ewes en ecm arcane een Soma SoS mannan ana e 

Kernel Mode Dispatcher Offset PLVSL_KERNEL 
+ See eee S eS SSS eS SSeS eeeecoece seceeece + 

Exec Mode Entry Offset PLVSL_EXEC 
$eweneccoscsocccecceccccewcceccscesceccccce + 

User Rundown Service Offset PLV$L_USRUNDWN 
$owcesesenccoceesccocecccs ween wenn e-ee-ee + 

Reserved 
$eweweeeewweewwcewwewweceeccecccccccccccce + 

RMS Dispatcher Offset PLVSL_RMS 
$ewececceecscecccecccecccecesecceccecsceece + 

Address Check } PLVSL_CHECK 
jeocnascuaesecrsunncesesencoussesensssesces + 


The reference to SYS$K_VERSION will only be resolved *° the image is 
Linked against SYS.STB. In other cases the version check is 
unnecessary and will not be done. 

-WEAK SYS$K_VERSION 


PSECT USER_SERVICES,PAGE VEC PIC ,NOWRT EXE 


-LONG PLVSC_TYP_CMOD 3 Set type of vector to change mode dispatcher 
ON $k" VERSION : Identify systen version 

ONG KERNEC_DISPATCH-. 3 Offset to kernel mode dispatcher 

ONG EXEC_DISPATCH-. ; Offset to executive mode dispatcher 
G USER_RUNDOWN-. ; Offset to user rundown service 


De eee) 
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-LONG Q ; Reserved. 
LONG 8 3 No RMS dispatcher 
- LONG 3; Address check = PIC image 


» PAGE 
-SBTTL Kernel Mode Dispatcher 
Input Parameters: 


aa 
+ 


(SP) = Return address if bad change mode value 
RO = Change mode argument value. 


R4 = Current PCB Address. (Therefore R4 must be specified in all 
register save masks for kernel routines.) 


AP - nek ag pointer existing when the change 
mode instruction was executed. 


FP = Address of minimal cail frame to exit 
the change mode dispatcher and return to 
the original mode. 

-PSECT SER FEEL. DESIST TE MOUNT ENE oP 


ernel access violation 
MOVZWL #SS$_ACCVIO,RO 


; Set access violation status code 
and return 

; Kernel insufficient arguments. 

; Set status code and 


return 
; RSB to forward request 


VZWL  #SS$_INSFARG,RO 
KNOTME: RSB 


nx 
_ 
2 
n” 
nn” 
Pd 
xz 
a 
Bete Se te eee 


KERNEL_DISPATCH:: 3; Entry to dispatcher 
MOVAB W*-KCODE_BASE(RO).R1 3; Normalize dispatch code value 
BLSS KNOTM ; Branch if code value too low 
CMPW . R1,#KERNEL_COUNTER ; Check nigh Limit 
BGEQU KNOTME ; Branch if out of range 


The dispatch code has now been verified as being handled by this dispatcher, 
now She Srqunank List will be probed and the required number of arguments 
verified. 


MOVZBL W*KERNEL_NARGCR1),R1 3; Get required argument count 
a#4(R1),R1 : 


MOVAL ° ; Compute byte count yee din arg count 
IFNORD R1,(AP) ,KACCVIO ; Branch if orpe ast not readable 
CMPB = (AP) ,W*<KERNEL_NARG-KCODE_BASE>CROJ ; Check for required number 
BLSSU KINSFARG 37 of arguments 
MOVL FP,SP 3; Reset stack for service routine 
CASEW RO,- ; Case on change mode 
- 3 argument value 
#KCODE BASE ,- ; Base value 
#<KERNEL_COUNTER=1> ; Limit value (number of entries) 
KCASE _BASE: ; Case table base address for DEFINE_SERVICE 
3 Case table entries are made in the PSECT USER_KERNEL_DISP1 by 
3 invocations of the ee SERVICE macro. The three PSECTS,. ; 
3 USER_KERNEL_DISPO,1,2 wilT be abutted in lexical order at (ink-time. 


2 ees 
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-PSECT USER _KERNEL_DISP2,BYTE,NOWRT,EXE,PIC 

BUG_CHECK IVSSRVRQST,FATAL ; Since the change mode code is validated 
PAGE ; above, we should never get here 

/SBTTL Executive Mode Dispatcher 


Input Parameters: 


- 
> 


(SP) = Return address if bad change mode value 
RO = Change mode argument value. 


AP = Argument pointer existing when the change 
mode instruction was executed. 


FP = Address of minimal call frame to exit 
the change mode dispatcher and return to 
the original mode. 


-PSECT USER_EXEC_DISPO,BYTE ,NOWRT,EXE,PIC 

EACCVIO: ; Exec access violation 
MOVZWL #SS$_ACCV1O,RO ; Set access violation status code 
RET ; _and return 

EINSFARG: ; Exec insufficient arguments. 


MOVZWL #SS$_INSFARG,RO ; Set status code and 
RET ; return 
ENOTME: RSB ; RSB to forward request 
EXEC_DISPATCH:: ; Entry to dispatcher 
MOVAB 


W*-ECODE_BASE (RO) ,R1 ; Normalize dispatch code value 
BLSS ; Branch if code value too low 
CMPW R1,#EXEC_COUNTER 3; Check high Limit 
BGEQU ENOTME ; Branch if out of range 


; The dispatch code has now been verified as being handled by this dispatcher, 
; ae Fy ar ganees List will be probed and the required number of arguments 
; verified. 


MOVZBL W*EXEC_NARGCR1),R1 : Get required argument count 
MOVAL a#4(R1J,R1 ; Compute byte count including arg count 
IFNORD R1,(AP),EACCVIO ; Branch arglist not readable 
CMPB (AP) W*<EXEC_NARG-ECODE_BASE>CRO) ; Check for required number 
BLSSU  EINSF ARG ; _of argument 
MOVL FP,SP ; Reset stack fof service routine 
CASEW =RO,- ; Case on change mode 
- 3; argument value 
#E CODE _BASE ,- : Bese value 
#<EXEC~COUNTER-1> ; Limit value (number of entries 


) 
ECASE _BASE: :; Case table base address for DEFINE_SERVICE 
Case table entries are made in the PSECT USER_EXEC_DISP1 by 
invocations of the DEFINE SERVICE macro, The three PSECTS, 
USER_EXEC_DISPO,1,2 will Be abutted in lexical order at Link-time. 


-PSECT USER_EXEC_DISP2,BYTE ,NOWRT EXE ,PIC 


14 
USSDISP.MAR; 2 16-SEP-1984 17:06:34. 74 Page 8 


BUG _CHECK IVSSRVRQST,FATAL ; Since the eet mode code is validated 


; above, we should never get here 


. PAGE 
a -SBTTL User Rundown Service 


Functional description: 
This service is invoked from within the kernel mode system service 
that performs image rundown. It is invoked before any system 
rundown functions (i.e. deassign channels, release memory) are 
performed. User code should not invoked ~ RMS services or RTL 
routines, must not signal any exceptions. User code can invoke 
most system services execpt those that use RMS (e.g. SPUTMSG). 


msiabahaae sequence: 
SB USER_RUNDOWN 
Entered at IPL=0 and must leave at IPL=0. 
Input Parameters: 
R4 = Current PCB Address. (Therefore K4 must be specified in all 
register save masks for kernel routines.) 
R7 = Access mode parameter to SRUNDWN maximized with previous mode 


AP = Argument pointer existing when the SRUNDWN system 
service was invoked. 


4(AP) = Access mode parameter to SRUNDWN 


-PSECT USER_CODE BYTE ,NOWRT EXE ,PIC 


USER_RUNDOWN: : ; Entry point for service 
PUSHL R2 ; Save a eeereeee 
PUSHAB B“SYSOUT ; Set up address of descriptor 
PUSHL S“*#SYS_LEN ; Set up a he 
MOVAL <=(SP ; Grab some temporary scorer 
yt dae 4 4(R2), (R2) 3 poole a channel to operator console 
rror 


L . 
$OUTPUT  (R2), S*#MSG_LEN, B°MSG : P 

SDASSGN_S (R2) ; Get rid of the channel 
ADDL2 “#12, SP > Cl 


10$: ean up 
are (SPS+, R2 ; Restore register 


SysouT: .ASCII /_OPAO:/ 
SYS_LEN=.-SYSOUT 
G: aati? /eee Image exiting ***/ 


z 
“ 
° 


[SBTTL Get Time of Day Register Value 


; Functional Description: 

3 This routine reads the content of the hardware time of day 
3 processor register and stores the resulting value at the 

: specified address. 


rint the message on operator console 


XAD 
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Input Parameters: 
O4(AP) = Address to return time of day value 
RG = Address of current PCB 


Output Parameters: 
RO = Completion Status Code 


-ENTRY USER GET_TODR,*M<R2,R3,R4> 
MO R1 ; 


MOVL § #SS$_NORMAL,RO Set normal completion status 


VL ; Get address to store time of day register 
IFNOWRT #4, (R1),10$ : Branch if not writable fii 
JSB G*EXESREAD_TODR ; Call cpu-dependent routine 
MOVL ; Return current time of day register 
RET : and return 
108: a #SS$_ACCVIO,RO ; Indicate access violation 
. PAGE : 


-_ -SBTTL Set Page Fault Cluster Factor 


Functional Description: 
his routine sets the page fault cluster to the specified value 
and returns the previous value. 


Input Parameters: 
O4(AP) = New value for Page Fault Cluster factor 
OB(AP) = Address to return previous value 
(0 means none) 
R4 = PCB address of current process 


Output Parameters: 
RO = Completion Status code 


-ENTRY USER_SET_PFC,“M<R4,R5> 
MOVL @4CTCSGL_PHD,RS 
8(AP),R1 


Get address of process header 

Get address to store previous value 

Branch if none 

Branch if not writable 

Return current value 

Get new value for PFC 

Check for legal value 

Branch if legal 

Set to maximum value 

Set new value into PHD 

Set normal completion status 
and return 


L 1 
IFNOWRT #4,(R1 


),30$ 
MOVZBL PHO$B_DFPFC(RS),(R1) 
10$: MOVB  4(AP)7RO 


CMPB RO,#187 


@ 
io 
<m 
oo 
Cc 
~ 


#127,R0 
20$:  MOVB RO,PHD$B_DFPFC(RS) 
MOVL § #SS$_NORMAL,RO 


Indicate access violation 


30$: tama #SS$_ACCVIO,RO 


ba -SBTTL Null Service 
Functional Description: 


Input Parameters: 


+ 
7” Dx + 


QoQ 


: Output Parameters: 


+> 
cae 


NULL ,“M<> 3; Entry definition 
NORMAL ,RO : Set normal completion status 
; and return 


nm 


Be Se Ge Ge Fe Fe Se Oe Se Be Se Se Se He Se Be Se Se Se Se Se Se Se Se Se Se Se Se Se SP Se Se Se ee SH Be 
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